定義と使い方

PHPバージョン
4+

strpos()関数は
文字列の中から引数として渡された文字列を検索し、最初に見つかった（出現した）文字列のインデックスを返す関数です。引数として渡された文字列が見つからない場合はfalseを返します。

この関数は、文字列内で文字の位置を検索したり、含まれているかどうかを確認したりする際に便利です。

特徴

  • 大文字と小文字を区別します。
  • 日本語のようなマルチバイト（multi-byte）文字列には対応していません。
  • str_contains()関数が導入される前（PHP 8.0.0以前）は、文字列に含まれているかどうかを確認する際に、主にstrpos()関数が使用されていました。

補足説明
PHP 8.0.0で導入されたstr_contains()関数は、大文字と小文字を区別したうえで、文字列に指定した文字が含まれている場合はtrueを、含まれていない場合はfalseを返します。

基本例

PHP 
$str = 'Hello, World!';
$substring = 'World';

$pos = strpos($str, $substring);

if ($pos !== false) {
    echo "見つかった位置: $pos";
} else {
    echo '見つかりません。';
}

// 出力: 見つかった位置: 7

/*
 * 注意してください。
 * 文字列のインデックスは0から始まります。
 * 最初の文字のインデックスは0、2番目の文字のインデックスは1です。
 */

構文

PHP 
strpos(string $haystack, string $needle, int $offset = 0): int|false

引数

strpos()関数の引数の説明
$haystack 検索対象となる文字列です。
$needle 検索する文字列です。
  • 大文字と小文字を区別します。
  • PHP 8以前のバージョンでは、空文字列（''）は指定できません。Warningエラーが発生します。
$offset オプション。検索を開始する0ベースのインデックスです。
  • 省略した場合は、デフォルト値として0が使用されます。
  • PHP 7.1.0以降では負の値を指定でき、負の値を指定した場合は、文字列の末尾から数えた文字数の位置を基準に検索が開始されます。

戻り値

対象文字列の中で、指定した文字列（$needle）が最初に出現する位置（インデックス）を返します。
文字列の位置（インデックス）は1ではなく、0から始まる点に注意してください。

指定した文字列（$needle）が含まれていない場合はfalseを返します。

変更履歴

strpos()関数の変更履歴
バージョン説明
8.0.0 $needleに空文字列（''）を指定できるようになりました。
8.0.0 $needleに整数型（int）の値を渡す機能は、完全にはサポートされなくなりました。
7.3.0 $needleに整数型（int）の値を渡す機能は、使用中止（deprecated）となりました。
7.1.0 $offsetに負の値を渡せるようになりました。

注意点

strpos()関数は大文字と小文字を区別します。

PHP strpos()関数は大文字と小文字を区別します。 
$str = 'Hello, World!';
$substring = 'world';

$pos = strpos($str, $substring);

if ($pos === false) {
    echo "大文字と小文字が一致しないため、'world!'を見つけることができません。";
} else {
    echo "文字列に'world!'が含まれています。";
}

// 出力: "大文字と小文字が一致しないため、'world!'を見つけることができません。"

大文字と小文字を区別せずに文字列内で特定の文字列の位置を検索したい場合は、stripos()関数を使用してください。

文字列のインデックスは0から始まります。
最初の文字のインデックスは0で、2番目の文字のインデックスは1です。

PHP 文字列のインデックスは0から始まります。 
$newstring = 'abcdef ghijk';
$pos = strpos($newstring, 'a');

var_dump($pos); // int(0)

PHP 8以前のバージョンでは、検索する文字列に空文字列（''）を指定できません。

PHP PHP 8以前のバージョンでは、検索する文字列に空文字列（''）を許可していません。 
$str = 'Hello, World!';
$substring = '';

$pos = strpos($str, $substring); // Warning: strpos(): Empty needle in

PHP 8.0.0以降のバージョンでは、空文字列（''）を許可しています。

この関数の戻り値をBoolean型として使用する場合は注意が必要です。
この関数の戻り値をテストする際は、===演算子を使用してください。

対象文字列の中で、指定した文字列の位置が先頭にあると仮定してみましょう。

この場合、戻り値は0になります。

0は==演算子で比較するとfalseが返されます。
実際には指定した文字列が存在しているにもかかわらずfalseが返されてしまうため、戻り値をブール（boolean）型としてテストする場合は、厳密な型比較を行う必要があり、そのため===演算子を使用しなければなりません。

PHP Boolean型として戻り値を使用する場合は、===演算子を使用してください。 
$str = 'Hello, World!';
$substring = 'Hello';

$pos = strpos($str, $substring);

var_dump($pos); // int(0)

if ($pos === false) {
    echo "文字列に'Hello'が見つかりません。";
} else {
    echo "文字列に'Hello'が含まれています。";
}

// 出力: "文字列に'Hello'が含まれています。"

strpos()関数に日本語を適用した場合、日本語のようなマルチバイト文字列に対応していないため、意図しない結果が発生します。

補足説明
英語や数字などは1バイトですが、日本語や韓国語、中国語などは2バイト以上で表現されます。このように、2バイト以上で表現されるものを「マルチバイト（multi-byte）」と呼びます。

PHP 
$str = 'はじめまして。ようこそ！';
$substring = 'ようこそ';

$pos = strpos($str, $substring);

if ($pos !== false) {
    echo "見つかった位置: $pos";
} else {
    echo '見つかりません。';
}

// 出力: 見つかった位置: 21 ← 意図しない結果が発生します。

mb_strpos() 関数はstrpos()関数とほぼ同じ機能を持っていますが、日本語のようなマルチバイト文字列に対して安全に動作する機能を提供している点が大きな違いです。

日本語のようなマルチバイト文字列では、mb_strpos() 関数を使用してください。

例

strpos()関数は、大文字と小文字を区別して文字列を検索する際に使用されます。ここでは、strpos()関数のいくつかの活用例を見ていきましょう。

ファイルシステムおよびパス

ほとんどのファイルシステムは大文字と小文字を区別します。そのため、ファイル名やパスを正確に指定するには、大文字と小文字を区別する必要があります。

PHP 
$file_path = '/var/www/html/project/files/document.txt';
$directory_name = '/var/www/html/project';

// ファイルパスに特定のディレクトリが含まれているか確認
if (strpos($file_path, $directory_name) !== false) {
    echo 'ファイルは指定されたディレクトリに属しています。';
} else {
    echo 'ファイルは指定されたディレクトリに属していません。';
}

// 出力: 'ファイルは指定されたディレクトリに属しています。'

// ファイルパスからファイル名を抽出
$file_name = substr($file_path, strrpos($file_path, '/') + 1);
echo "ファイル名: $file_name";

// 出力: "ファイル名: document.txt"

この例では、strpos()関数を使用してファイルパスが特定のディレクトリを含んでいるかを確認し、substr()関数とstrrpos()関数を組み合わせて、ファイルパスからファイル名を抽出しています。

注意事項
ファイルパスに関連する作業では、実際のパスに対して正確な文字列操作が必要であり、パス操作に関して安全な方法を使用することが推奨されます。また、PHPではファイルパスを扱う際に、realpath()関数で正規化したり、pathinfo()関数でファイルパスの情報を取得したりする方法の方が、より安全で信頼性があります。

参考資料

関連項目